NetCloak 3.0 User's Guide: Using NetCloak With Other CGIs

	Version 3.0 User's Guide

Using NetCloak With Other CGIs	Previous \| Next Contents

Sometimes it is useful to use NetCloak in conjunction with another server add-on tool to process a single request. For example, you might have a page that is generated by a CGI linked to a database, but would like to include NetCloak commands in that page. This is called "CGI Chaining", and is made possible by NetCloak's ability to call other CGI applications.

NetCloak can call other CGIs in one of two ways, using either the EXEC_CGI command, or by creating a suffix mapping so that requests for a specified file type are automatically routed through NetCloak to a "back-end" CGI. The EXEC_CGI command is useful when you want to run more than one additional CGI for a particular page, or when you write a CGI that returns just a part of a page. For example, you could write an AppleScript CGI that generated some random phrase to be inserted into your HTML page. Instead of returning an entire page (HTTP header and all), your script could return only the phrase it was written to create. The result of your script would then be read and inserted into the page as the page is processed by NetCloak. Any NetCloak commands in the response from the CGI will also be processed by NetCloak. For information on exactly how to use the EXEC_CGI command, see the "Commands" section.

In addition to executing a CGI as simply one part of an entire page, NetCloak can also accept entire pages generated by other CGIs and parse the NetCloak commands that appear in the resulting page. For example, if you wanted to include NetCloak commands within a NetForms response page, you would set up NetForms as a "back-end" to NetCloak.

How It Works

When a request comes in to the Web server and is dispatched to NetCloak, NetCloak checks to see if the file should be handled by another CGI. If so, NetCloak immediately passes the request off to the appropriate CGI. The back-end CGI handles the request normally, but instead of returning the response page to your web server, it returns the response page to NetCloak. NetCloak then receives the page, processes any NetCloak commands that appear in the page and returns the final result to the Web server, which sends the response to the client.

Figure 1: Flow of back-end CGI requests from the Browser to the Back-End CGI through NetCloak.

In the case of NetForms, there is a response file that is sent from NetForms after a form has been submitted. If NetForms is set up as a back-end to NetCloak, the Web server sends the form data to NetCloak, which sends the data to NetForms for processing. NetForms returns a response page to NetCloak, which processes the NetCloak commands in the page and returns the resulting page to the Web server.

Defining Back-End CGIs

To set up a back-end CGI, you must:

Make sure that the action that defines how your Web server is going to handle the request points to NetCloak. For example, NetForms files usually end in ".FDML". To use NetForms as a back-end CGI, the URL suffix ".FDML" must use NetCloak for processing. Note that the Web server will be sending these requests to NetCloak, not the CGI being back-ended! All CGI actions that will be cloaked must be referred directly from the Web server to NetCloak.
Add a line to the "NetCloak.bsm" file. "BSM" stands for "Back-end Suffix Mapping". This file tells NetCloak where to send requests that end with a particular suffix. It is made up of a file suffix (beginning with a period) and then the name of and path to the CGI application to be called. Here is an example ".BSM" file:
```
    .Q      :Tango.acgi
    .FDML   :NetForms.acgi
    .RSP    :Responder.cgi
```
In this case, URLs with a suffix of ".Q" will be sent to "Tango.acgi", URLs with a suffix of ".FDML" will be sent to "NetForms.acgi", and those ending in ".RSP" will be sent to "Responder.cgi". The pathnames must be relative to the Root folder, and begin with a colon or slash.
Again, note that in your Web server software, all of these suffix mappings should be directed to NetCloak so that NetCloak can hand off the request and then process the results.

A few additional notes:

When you give NetCloak the name of a CGI to execute in the ".BSM" file, the filename must be that of the actual application. The filename can't be a file that is to be processed by an application or an alias to the CGI. You must tell NetCloak the full, exact name of the CGI application to be executed.

If the CGI is not in the same folder as NetCloak, you must specify a pathname for the CGI. Like aliases, pathnames in the NetCloak.bsm file must be paths relative to the root folder configured in NetCloak, and must start with a slash or colon. File and folder names in the pathname may be separated by slashes or colons.

You may use the ".BSM" file to specify up to thirty-two back-end CGIs.

Because of the extra overhead involved, back-ending CGIs can cause a noticeable decrease in performance on your server for pages served from a back-end CGI. We recommend that you use care to only use back-end CGIs when needed. If another CGI does not require the use of NetCloak commands, don't set it up as a back-end CGI.

URLs that call CGIs by referring to them directly can be run through NetCloak without setting up a line in the ".BSM" file. Set your Web server software to send all ".CGI" or ".ACGI" requests to NetCloak and it will automatically pass these URL requests to the specified CGI application and process the results.

Query or Path arguments specified in the URL will be preserved when NetCloak calls the back-end CGI, up to a maximum of 1024 characters. Post arguments are preserved up to a limit of 24Kb. This limit is the same as in WebSTAR.

If the error file setting of your Web server is set to use a CGI, NetCloak will automatically route invalid requests to it and process any NetCloak commands in the page returned by the error CGI.

Troubleshooting Back-End Setups

If you have trouble setting up a CGI as a back-end CGI, make sure that the CGI executes correctly by itself first. Set up your Web server to call it directly, without going through NetCloak. If that doesn't help solve the problem, try temporarily replacing the CGI with the "Responder.cgi" application. Responder is handy because it shows you exactly what is being sent to the CGI. Move the CGI you are trying to back-end and copy and rename Responder in its place. If Responder works as the back-end CGI, then chances are good that your set-up is correct. If Responder doesn't return a meaningful page, then go back and check your Web server and ".BSM" settings. You can download Responder from the Maxum Web site at www.maxum.com.

You may also need to change settings in the CGI you are attempting to run as a back-end. Some CGIs require configuration changes to operate properly as a back-end to NetCloak. Tango from EveryWare Development is a notable example.

Back-Ending Plug-Ins With PIXO

When using the NetCloak plug-in, you may also back-end other plug-ins that conform to the PIXO standard for inter-plug-in communication developed jointly by Maxum and ClearWay Technologies, Inc. In this case, the entry in the NetCloak.bsm file looks like this:

    .NQRY    TANGO_PIXO

where ".NQRY" is the file suffix that is mapped to the plug-in, and "TANGO_PIXO" is the name of the PIXO service registered by the plug-in (in this example, by the Tango 2.x plug-in). Check with the vendor of your other WebSTAR API plug-ins to see if they support PIXO. If they do, they can provide you with the exact name of their PIXO service.


Copyright © 1996-1999 Maxum Development Corporation http://www.maxum.com/	Previous \| Next Contents